Metadata-Version: 2.1
Name: better cryptography
Version: 0.6.1
Summary: A module for encryption and information security operations.
Home-page: UNKNOWN
Author: Wyatt Garrioch
Author-email: w.garrioch456@gmail.com
License: UNKNOWN
Keywords: python,encryption,AES,ciphers,encryption alogorithms,information security
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: POSIX :: Linux
Description-Content-Type: text/markdown

# Contents
 - `better-cryptography` provides a simplified interface for encrypting files, folders, and strings, and a simplified interface for generating ciphering objects across multiple cryptography libraries. The library also provides various functions and methods used in cryptography and information security.


 # FAQ

  ## How do I install and import the package?
  Install through the `pip3 install better-cryptography` command. Import via `import better_cryptography` or `from better_cryptography import ...`.


  ## How do I report a bug?
  Email me at w.garrioch456@gmail.com.

# Syntax
  

   - `hash_(StringToHash:str, hash_code:str, return_type="hex")`

     A function for simplifed interaction with the inbuilt `hashlib` module.
    
     - #### Parameters:

       - `StringToHash`: The string to be hashed by the function.

       - `hash_code`: A string indicating which type of hash to use. 
      
         - Currently support hash codes are:
           
           - SHA 512; hash_code = "SHA512"

           - SHA 256; hash_code = "SHA256"

           - SHA 224; hash_code = "SHA224"

           - MD5; hash_code = "MD5"

       - `return_type`: An optional parameter specifying what to return the hash in. Defaults to hexadecimal. To change to bytes, set `return_type` to "bytes".

     Returns: either a hexadecimal or byte hash of `StringToHash`.

   - `random_choice(given_list)` 
    
     A function to randomly select an item from a list.

     - Parameters:
       - `given_list`: The list that the function is choosing from.

     Returns: an item randomly chosen from the list.

   - `compare_hashes(hash1:str, hash2:str)`

     A function to compare 2 hashes/strings, in such a way to reduce the chance of a successful timing attack.

     - Parameters:

         - `hash1`: The first string to be compared to.

         - `hash2`: The string to compare to `hash1`.

     Returns: A boolean value based on whether the two strings are identical.

   - `token_generate(size:int, return_type="HEX")`

     A function to generate a token of n `length` in type `return_type`.

     - Parameters

       - `size`: an integer indicating how long the returned token should be.
       
       - `return_type`: A string indicating what to return the token as. Supported modes are `"URL"`, `"HEX"`, and `"BYTES"`. Defaults to hexadecimal.

     Returns: a random token as either a hexadecimal string, URL-safe string, or bytes.
     
   - `gen_random_password(length:int)`
       
     A function to generate random passwords of n `length`.

     - Parameters
         
       - `length`: The length of the password.

     Returns: a password of the specified length.

   - `sec_delete(file_path, random_fill = True, null_fill = True, passes = 35)`
       
     A function to securely delete a file.

     - Parameters

       - `file_path`: The path of the file as a string.

       - `random_fill`: Boolean value; indicates whether or not to overwrite the file with random data. Defaults to True.

       - `null_fill`: Boolean value; indicates whether or not to overwrite the file with null characters. Defaults to True.

       - `passes`: Integer; indicates how many times to overwrite the file with random/null data. Defaults to 35.

     Returns: an integer value indicating if the function executed.

   - `delete(path:str)`

     A file deletion function.

     - Parameters:
       
       - `path`: The path of the file to be deleted.

     Returns: an integer indicating if the the function successfully executed.

   - # Ciphers Class

     - The Ciphers class provides a simplifed way of doing various ciphering operations. 
       
       Such functions include RSA string encryption, RSA key pair generation, symmetric key generation, encryption/decryption of files with AES or Blowfish in CFB mode, and encryption/decryption of files with the `cryptography` module's `Fernet` class.

     - ## Ciphers Methods

       - ### Miscellenious Methods

         These methods are utility functions, such as key generation and encryption password changing.

         - `generate_symmetric_key(salt=None)`
           
           A method for generating a symmetric key with the class `password` attribute and argument `salt` using PBKDF2. Will return a tuple of `(key, salt)` if the salt is not provided.

           - Parameters

             - `salt`: an optional argument for the salt to be used during key generation. Will default to 32 securely generated bytes if salt is not provided.

           Returns: the generated key.

         - `generate_FerNet_key()`

           Method for generating a FerNet key. Takes no arguments, and returns the key in bytes format.
        
         - `change_encrypting_password(old_password:str, new_password:str)`
           
           Method for changing the classes' `password` attribute.

           - Parameters:
             
             - `old_password`: The old password. Must match the class `password` attribute.

             - `new_password`: The password the replace the class `password` attribute with.

           Returns: 1, if the `old_password` parameter does not match the class `password` attribute.
           Returns 0 if the password change was successful.

       - ### RSA functions
         These functions are for RSA ciphering operations and include string encryption/decryption and RSA key pair generation.

         - `generate_RSA_keys()`

           A method for generating a RSA public/private key pair. 
           
           Takes no arguments and returns the key pair in a tuple `(public_key, private_key)`.

         - `RSA_encrypt_string(public_key, str_)`

           A method for encrypting the `str_` parameter with RSA using the `public_key` parameter.

           - Parameters:

             - `public_key`: The public key of a RSA key pair.

             - `str_`: The string to be encrypted.

           Returns: the encrypted string, in bytes format.

         -  `RSA_decrypt_str(private_key, encrypted_str:bytes)`
           
             A method for decrypting an encrypted bytestring that was encrypted using RSA, given the private key of a RSA key pair.

             - Parameters:

               - `private_key`: The private key of a RSA key pair.

               - `encrypted_str`: The encrypted bytestring.

             Returns: The decrypted string.
         
       - ### AES functions

         These functions include file and string encryption/decryption in AES CFB.

         - `AES_encrypt_file(path)`

           A method for encryption of a file or folder with the AES encryption alogorithm in CFB mode.

           - Parameters:

             - `path`: The path to the file or folder to be encrypted, in string format.

           Returns:
             
             0: File encryption successful.

             1: File path is None.

             2: File path is invalid.

             3: Program does not have permission to access file.

             4: The file or folder is hidden.

             5: The file is part of a Linux root filesystem.

             6: An encrypted file marker was detected during encryption.

         - `AES_decrypt_file(path)`

           A method for decrypting an already encrypted file or folder using AES in CFB mode.

           - Parameters:

             - `path`: The path to the encrypted file or folder, in string format.

           Returns:

           0: File decryption successful.

           1: File path is None.

           2: File path is invalid.

           3: Program does not have permission to access file.

           4: File is hidden.

           5: File is part of Linux root filesystem.

           6: File was encrypted with a different key.

           7: File was not encrypted.

           8: File was encrypted with a different alogrithm.

         - `AES_encrypt_string(string_to_encrypt:bytes, key=None)`

           A method for encrypting a string with AES in CFB mode.

           - Parameters:

             - `string_to_encrypt`: The string to be encrypted, in bytes format.

             - `key`: The key to use during encryption. If not provided, it defaults to None and generates its own key.

           Returns: A tuple of `(ciphered_string, intialization_vector, key)`

         - `AES_decrypt_string(encrypted_string:bytes, key_bytes, iv:bytes)`

           A method for decrypting string using AES in CFB mode.

           - Parameters:

             - `encrypted_string`: The string to be decrypted, in bytes format.

             - `key`: The key used to encrypt the string. Will raise `NoKeyError` if None.

             - `iv`: The intialization vector used in the cipher. Will raise `InvalidCipherArgument` if None. 

           Returns: The decrypted string in bytes format.


       - ### Blowfish functions

         These functions include file and string encryption/decryption in Blowfish CFB.

         - `BLO_encrypt_file(path:str)`

           A method for encryption of a file or folder with the Blowfish alogorithm in CFB mode.

           - Parameters:

             - `path`: The path to the file or folder, in string format.

           Returns:

             0: File encryption successful.

             1: File path is None.

             2: File path is invalid.

             3: Program does not have permission to access file.

             4: File is hidden.

             5: File is part of a Linux root filesystem.

             6: File encryption marker detected during encryption.

         - `BLO_decrypt_file(path:str)`

           A method for decrypting an already encrypted file or folder using the Blowfish Encryption algorithm in CFB mode.

           - Parameters:

             - `path`: The path of the file, in string format.

           Returns:

             0: File decryption successful.

             1: File path is None.

             2: File path is invalid.

             3: Program does not have permission to access file.

             4: File is hidden. 

             5: File is a part of a Linux root filesystem.

             6: File was encrypted with a different key.

             7: File was not encrypted.

             8: File was encrypted using a different alogrithm.

         - `BLO_encrypt_string(string_to_encrypt:bytes, key=None)`

           A method to encrypt a string using the Blowfish encryption algorithm in CFb mode.

           - Parameters:

             - `string_to_encrypt`: The string to be encrypted, in bytes format.

             - `key`: The key to be used during encryption. If not provided, it defaults to None and generates a new key.

           Returns: a tuple of `(ciphered_string, intialization_vector, key)`.

         - `BLO_decrypt_string(encrypted_string:bytes, key:bytes, iv:bytes)`

           A method for decrypting an already encrypted string using the Blowfish encryption alogorithm in CFB mode.

           - Parameters:

             - `encrypted_string`: The string to be decrypted, in string format.

             - `key`: The key used to encrypt the string. Will raise `NoKeyError` if the key is None.

             - `iv`: The intialization vector used in the cipher. Will raise `InvalidCipherArgument` if the IV is None.

           Returns: The decrypted string in bytes format.


       - ### FerNet functions

         These functions include file and string encryption/decryption using the `cryptography` module's `Fernet` class.

         - `FerNet_encrypt_file(path:str, key:bytes)`

           A method for encryption of a file or folder using the `Fernet` Class.

           - Parameters:

             - `path`: The path to the file or folder, in string format.

             - `key`: The key to be used for encryption.

           Returns:

             0: File encryption successful.

             1: File path is None.

             2: File path is invalid.

             3: Program does not have permission to access file.

             4: File is hidden.

             5: File is part of a Linux root filesystem.

             6: File encryption marker detected during encryption.

         - `FerNet_decrypt_file(path:str, key:bytes)`

           A method for decrypting an already encrypted file or folder using the Blowfish Encryption algorithm in CFB mode.

           - Parameters:

             - `path`: The path of the file, in string format.

             - `key`: The key used to encrypt the file.

           Returns:

             0: File decryption successful.

             1: File path is None.

             2: File path is invalid.

             3: Program does not have permission to access file.

             4: File is hidden. 

             5: File is a part of a Linux root filesystem.

             6: File was encrypted with a different key.

             7: File was not encrypted.

             8: File was encrypted using a different alogrithm.

         - `FerNet_encrypt_string(bstring:bytes, key=None)`

           A method to encrypt a string using the Blowfish encryption algorithm in CFb mode.

           - Parameters:

             - `bstring`: The string to be encrypted, in bytes format.

             - `key`: The key to be used during encryption. If not provided, it defaults to None and generates a new key.

           Returns: a tuple of `(ciphered_string, key)`.

         - `FerNet_decrypt_string(encrypted_string:bytes, key:bytes)`

           A method for decrypting an already encrypted string using the Blowfish encryption alogorithm in CFB mode.

           - Parameters:

             - `encrypted_string`: The string to be decrypted, in string format.

             - `key`: The key used to encrypt the string. Will raise `NoKeyError` if the key is None.

           Returns: The decrypted string in bytes format.


   - # Cipher_Constructor Class
     
     This class provides a simplified interface for generating cipher objects.

     - ## Methods

       - `intialize_AES_cipher(mode:str, key:bytes, iv=None, nonce=None)`

         Method for generating an AES cipher object from the `pycryptodome` library.

         - Parameters:

           - `mode`: The mode to set the cipher as, in string format.

             Current modes are:
             
               - `CFB`
  
               - `CBC`

               - `CTR`

               - `ECB`

               - `OFB`

               - `OPENPGP`

               - `CCM`

               - `EAX`
  
               - `GCM`
  
               - `OCB`

           - `key`: The key to use for the cipher. 

           - `iv` and `nonce`: basic parameters for respective ciphers. If a nonce/IV is needed and is not provided, the library will raise an `InvalidCipherArgument` error.

         Returns: A cipher object of the specified mode, using the specified IV/nonce and encrypting with the specified key.
        
       - `intialize_FerNet_cipher(key:bytes)`

         Method for generating a Fernet cipher.

         - Parameters:

           - `key`: The key to intiate the Fernet cipher with.

         Returns: a Fernet cipher object.

   - # Log class

   This class is the `better-cryptography` default logging class. It provides basic write-to files and log file creatiion. Linux native.
   
   It requires a username on instantiation.

   - ## Methods

     - `log_exists()`
       
       A method for checking if a log file exists. Takes no arguments and returns a boolean value. Will raise an `UnknownFilesystem` error if the OS is not Linux.

     - `create_log()`

       A method for creating a log file in the given users `/home/` directory. Takes no arguements and returns 0. Will raise an `UnknownFilesystem` error if the OS is not Linux.
    
     - `audit(keywords:list)`

       Removes lines from a .log file if they contain a word in the `keywords` list. returns 0.  Will raise an `UnknownFilesystem` error if the OS is not Linux.

     - `log(logstring:str)`

       Writes `logstring` to the .log file of the specified user. Will raise an `UnknownFilesystem` error if the OS is not Linux.

     - `change_user(new_user:str)`

       Changes the class `username` attribute to `new_user`.

